3 Retrieving URLs

The url library defines the following three functions for retrieving the data specified by a URL. The actual retrieval protocol depends on the URL’s URI scheme, and is performed by lower-level scheme-specific functions. (Those lower-level functions are not documented here, and generally should not be called directly.)

In each of these functions, the url argument can be either a string or a parsed URL structure. If it is a string, that string is passed through url-encode-url before using it, to ensure that it is properly URI-encoded (see URI Encoding).

Function: url-retrieve-synchronously url silent no-cookies

This function synchronously retrieves the data specified by url, and returns a buffer containing the data. The return value is nil if there is no data associated with the URL (as is the case for dired, info, and mailto URLs).

If the optional argument silent is non-nil, progress messages are suppressed. If the optional argument no-cookies is non-nil, cookies are not stored or sent.

Function: url-retrieve url callback &optional cbargs silent no-cookies

This function retrieves url asynchronously, calling the function callback when the object has been completely retrieved. The return value is the buffer into which the data will be inserted, or nil if the process has already completed.

The callback function is called this way:

(apply callback status cbargs)

where status is a plist representing what happened during the retrieval, with most recent events first, or an empty list if no events have occurred. Each pair in the plist is one of:

(:redirect redirected-to)

This means that the request was redirected to the URL redirected-to.

(:error (error-symbol . data))

This means that an error occurred. If so desired, the error can be signaled with (signal error-symbol data).

When the callback function is called, the current buffer is the one containing the retrieved data (if any). The buffer also contains any MIME headers associated with the data retrieval.

If the optional argument silent is non-nil, progress messages are suppressed. If the optional argument no-cookies is non-nil, cookies are not stored or sent.

Function: url-queue-retrieve url callback &optional cbargs silent no-cookies

This function acts like url-retrieve, but with limits on the number of concurrently-running network processes. The option url-queue-parallel-processes controls the number of concurrent processes, and the option url-queue-timeout sets a timeout in seconds.

To use this function, you must (require 'url-queue).

User Option: url-queue-parallel-processes

The value of this option is an integer specifying the maximum number of concurrent url-queue-retrieve network processes. If the number of url-queue-retrieve calls is larger than this number, later ones are queued until earlier ones are finished.

User Option: url-queue-timeout

The value of this option is a number specifying the maximum lifetime of a url-queue-retrieve network process, once it is started. If a process is not finished by then, it is killed and removed from the queue.